java - 日志

在SpringBoot项目中使用MDC实现日志traceId

在项目中，对于每一次请求，我们都需要一个 traceId 将整个请求链路串联起来，这样就会很方便我们根据日志排查问题。但是如果每次打印日志都需要手动传递 traceId 参数，也会很麻烦， MDC 就是为了解决这个场景而使用的。

注：这里我们使用 slf4j + logback

设置traceId

1.使用filter过滤器设置traceId

新建一个过滤器，实现Filter，重写init，doFilter，destroy方法，设置traceId放在doFilter中，在destroy中调用MDC.clear()方法。

java

@Slf4j
@WebFilter(filterName = "traceIdFilter",urlPatterns = "/*")
public class traceIdFilter implements Filter {
    @Override
    public void init(FilterConfig filterConfig) throws ServletException {
    }

    @Override
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain)
            throws IOException, ServletException {
        MDC.put("traceId", UUID.randomUUID().toString().substring(0,8));
        filterChain.doFilter(request, servletResponse);
    }

    @Override
    public void destroy() {
    	MDC.clear();
    }
}

2.使用JWT token过滤器的项目

springboot项目经常使用spring security+jwt来做权限限制，在这种情况下，我们通过新建filter过滤器来设置traceId，那么在验证token这部分的日志就不会带上traceId，因此我们需要把代码放在jwtFilter中。

java

/**
 * token过滤器 验证token有效性
 *
 * @author china
 */
@Component
public class JwtAuthenticationTokenFilter extends OncePerRequestFilter {
    @Autowired
    private TokenService tokenService;

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws ServletException, IOException {
        MDC.put("traceId", UUID.randomUUID().toString().substring(0,8));
        LoginUser loginUser = tokenService.getLoginUser(request);
        if (StringUtils.isNotNull(loginUser) && StringUtils.isNull(SecurityUtils.getAuthentication())) {
            tokenService.verifyToken(loginUser);
            UsernamePasswordAuthenticationToken authenticationToken = new UsernamePasswordAuthenticationToken(loginUser, null, loginUser.getAuthorities());
            authenticationToken.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
            SecurityContextHolder.getContext().setAuthentication(authenticationToken);
        }
        chain.doFilter(request, response);
    }
    
    @Override
    public void destroy() {
        MDC.clear();
    }
}

第二种写法

java

/**
 * 生成traceId用的
 */
@Component
@Slf4j
public class TraceIDFilter extends OncePerRequestFilter {

    @Autowired
    private CloudWatchApi cloudWatchApi;

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        try {
            try{
                String traceId = MDC.get("traceId");
                if(traceId == null){
                    MDC.put("traceId", UUID.randomUUID().toString().substring(0,8));
                }
            }catch (Exception e){
                log.error("generate traceId error", e);
            }
            filterChain.doFilter(request, response);
        } finally {
            try{
                MDC.remove("traceId");
            }catch (Exception e){
                log.error("remove traceId from MDC error", e);
            }
        }
    }
}

3.使用Interceptor拦截器设置traceId

定义一个拦截器，重写preHandle方法，在方法中通过MDC设置traceId

java

/**
 * MDC设置traceId拦截器
 *
 * @author china
 */
@Component
public abstract class TraceIdInterceptor extends HandlerInterceptorAdapter {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        MDC.put("traceId", UUID.randomUUID().toString().substring(0,8));
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, @Nullable Exception ex) throws Exception {
        MDC.clear();
    }
}

logback.xml中配置traceId

与之前的相比只是添加了[%X{TRACE_ID}]， [%X{***}]是一个模板，中间属性名是我们使用MDC put进去的。

xml

#之前
<property name="log.pattern" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{20} - [%method,%line] - %msg%n" />
#增加traceId后
<property name="log.pattern" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{20} - [%method,%line] - [%X{TRACE_ID}] - %msg%n" />

补充异步方法带入上下文的traceId

异步方法会开启一个新线程，我们想要是异步方法和主线程共用同一个traceId，首先先新建一个任务适配器MdcTaskDecorator。

java

public class MdcTaskDecorator implements TaskDecorator 
    /**
     * 使异步线程池获得主线程的上下文
     * @param runnable
     * @return
     */
    @Override
    public Runnable decorate(Runnable runnable) {
        Map<String,String> map = MDC.getCopyOfContextMap();
        return () -> {
            try{
                MDC.setContextMap(map);
                runnable.run();
            } finally {
                MDC.clear();
            }
        };
    }
}

然后，在线程池配置中增加executor.setTaskDecorator(new MdcTaskDecorator())的设置

java

 /**
 * 线程池配置
 *
 * @author china
 **/
@EnableAsync
@Configuration
public class ThreadPoolConfig {
    private int corePoolSize = 50;
    private int maxPoolSize = 200;
    private int queueCapacity = 1000;
    private int keepAliveSeconds = 300;

    @Bean(name = "threadPoolTaskExecutor")
    public ThreadPoolTaskExecutor threadPoolTaskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setMaxPoolSize(maxPoolSize);
        executor.setCorePoolSize(corePoolSize);
        executor.setQueueCapacity(queueCapacity);
        executor.setKeepAliveSeconds(keepAliveSeconds);
        executor.setTaskDecorator(new MdcTaskDecorator());
        // 线程池对拒绝任务(无线程可用)的处理策略
        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
        return executor;
    }
}

最后，在业务代码上使用@Async开启异步方法即可

java

@Async("threadPoolTaskExecutor")
void testSyncMethod();

在接口返回数据中，增加traceId字段

在接口返回都使用了一个t自定义类来包装，所以只需要把这个类的构造器中增加traceId返回即可，相对简单。

java

/**
 * 日志跟踪标识
 */
private static final String TRACE_ID = "TRACE_ID";

/**
 * 初始化一个新创建的 AjaxResult 对象，使其表示一个空消息。
 */
public AjaxResult() {
    super.put(TRACE_ID, MDC.get(TRACE_ID));
}

/**
 * 初始化一个新创建的 AjaxResult 对象
 *
 * @param code 状态码
 * @param msg  返回内容
 */
public AjaxResult(int code, String msg) {
    super.put(CODE_TAG, code);
    super.put(MSG_TAG, msg);
    super.put(TRACE_ID, MDC.get(TRACE_ID));
}

/**
 * 初始化一个新创建的 AjaxResult 对象
 *
 * @param code 状态码
 * @param msg  返回内容
 * @param data 数据对象
 */
public AjaxResult(int code, String msg, Object data) {
    super.put(CODE_TAG, code);
    super.put(MSG_TAG, msg);
    super.put(TRACE_ID, MDC.get(TRACE_ID));
    if (StringUtils.isNotNull(data)) {
        super.put(DATA_TAG, data);
    }
}

支持Feign

支持RestTemplate

线程池

需要单独处理Callable和Runnable，在外面包一层。由于线程池中的线程是复用的，所以在用完之后需要在finnally中清除设置的traceId，避免影响下一次任务

java

/**
 * 异步执行
 *
 * @param task 任务
 */
public void execute(Runnable task) {
    defaultThreadPoolExecutor.execute(wrap(task, MDC.getCopyOfContextMap()));
}

/**
 * 提交一个有返回值的异步任务
 */
public <T> Future<T> submit(Callable<T> task) {
    return defaultThreadPoolExecutor.submit(wrap(task, MDC.getCopyOfContextMap()));
} 


 * 封装 Runnable，复制 MDC 上下文
 */
private Runnable wrap(Runnable task, Map<String, String> contextMap) {
    return () -> {
        Map<String, String> previous = MDC.getCopyOfContextMap();
        if (contextMap != null) {
            MDC.setContextMap(contextMap);
        } else {
            MDC.clear();
        }
        try {
            task.run();
        } finally {
            // 恢复线程池线程原来的 MDC，避免影响下一次任务
            if (previous != null) {
                MDC.setContextMap(previous);
            } else {
                MDC.clear();
            }
        }
    };
}

/**
 * 封装 Callable，复制 MDC 上下文
 */
private <T> Callable<T> wrap(Callable<T> task, Map<String, String> contextMap) {
    return () -> {
        Map<String, String> previous = MDC.getCopyOfContextMap();
        if (contextMap != null) {
            MDC.setContextMap(contextMap);
        } else {
            MDC.clear();
        }
        try {
            return task.call();
        } finally {
            // 恢复线程池线程原来的 MDC，避免影响下一次任务
            if (previous != null) {
                MDC.setContextMap(previous);
            } else {
                MDC.clear();
            }
        }
    };
}

支持 MQ 消息（RabbitMq）

MQ的的话需要在sender时统一获取发送时的traceId，然后设置到mq的header中，然后利用Spring AMQP 提供了 RabbitListener 的 Advice 机制，可以对所有消费者统一处理，不需要在每一个consumer进行处理

消息生产者处理

java

/**
 * 同步发送mq （不管消费者有没有消费到，发出去消息就结束）
 *
 * @param typeEnum
 * @param message
 */
public <T> void sendMq(MqEnum.TypeEnum typeEnum, MqMessage<T> message) {
    rabbitTemplate.convertAndSend(MqEnum.Exchange.EXCHANGE_NAME, typeEnum.getRoutingKey(), message,
            msg -> {
                String traceId = MDC.get(TRACE_ID);
                if (traceId == null) {
                    traceId = UUID.randomUUID().toString().replace("-", "");
                    MDC.put(TRACE_ID, traceId);
                }
                msg.getMessageProperties().getHeaders().put(TRACE_ID, traceId);
                return msg;
            });
}

利用Advice机制获取发送来的traceId然后设置到当前消费者的线程中

java

/**
 * 透传MDC
 * sendMq时设置MDC到header中，消费端
 *
 * @return {@link Advice }
 * @author Czw
 * @date 2025/11/06
 */
@Bean
public Advice traceIdAdvice() {
    return (MethodInterceptor) invocation -> {
        Object[] args = invocation.getArguments();
        String traceId = null;

        for (Object arg : args) {
            if (arg instanceof Message message) {
                traceId = (String) message.getMessageProperties().getHeaders().get(TRACE_ID);
                break;
            }
        }

        if (traceId != null) {
            MDC.put(TRACE_ID, traceId);
        }

        try {
            return invocation.proceed();
        } finally {
            MDC.remove(TRACE_ID);
        }
    };
}

/**
 * 设置自定义的traceIdAdvice
 *
 * @param connectionFactory connectionFactory
 * @param traceIdAdvice     traceIdAdvice
 * @return {@link SimpleRabbitListenerContainerFactory }
 * @author Czw
 * @date 2025/11/06
 */
@Bean
public SimpleRabbitListenerContainerFactory rabbitListenerContainerFactory(
        ConnectionFactory connectionFactory,
        Advice traceIdAdvice) {
    SimpleRabbitListenerContainerFactory factory = new SimpleRabbitListenerContainerFactory();
    factory.setConnectionFactory(connectionFactory);
    factory.setAdviceChain(traceIdAdvice);
    return factory;
}

定时任务（xxljob）

仅处理XXL-Job的定时任务，利用全局 AOP 切面自动加 traceId，避免每个定时任务都去加

java

/**
 * @description:
 * @author: Czw
 * @create: 2025-11-07 15:17
 **/
@Aspect
@Component
publicclass XxlJobTraceAspect {

    @Pointcut("@annotation(com.xxl.job.core.handler.annotation.XxlJob)")
    public void xxlJobMethods() {}

    @Around("xxlJobMethods()")
    public Object aroundXxlJob(ProceedingJoinPoint joinPoint) throws Throwable {
        String traceId = UUID.randomUUID().toString().replace("-", "");
        MDC.put(TRACE_ID, traceId);
        try {
            return joinPoint.proceed();
        } finally {
            MDC.remove(TRACE_ID);
        }
    }
    privatestaticfinal String TRACE_ID = "traceId";
}

https://blog.csdn.net/weixin_38117908/article/details/107285978

https://www.cnblogs.com/strongmore/p/17964566

https://zhuanlan.zhihu.com/p/1992611875058374005

java - 日志 ​

设置traceId ​

1.使用filter过滤器设置traceId ​

2.使用JWT token过滤器的项目 ​

3.使用Interceptor拦截器设置traceId ​

logback.xml中配置traceId ​

补充异步方法带入上下文的traceId ​

在接口返回数据中，增加traceId字段 ​

线程池 ​

支持 MQ 消息（RabbitMq） ​

消息生产者处理 ​

定时任务（xxljob） ​

java - 日志

设置traceId

1.使用filter过滤器设置traceId

2.使用JWT token过滤器的项目

3.使用Interceptor拦截器设置traceId

logback.xml中配置traceId

补充异步方法带入上下文的traceId

在接口返回数据中，增加traceId字段

线程池

支持 MQ 消息（RabbitMq）

消息生产者处理

定时任务（xxljob）